docs: align ARC/DinD docs, spec, and schema with implementation#5890
Conversation
There was a problem hiding this comment.
Pull request overview
This PR corrects and expands ARC/DinD (split runner/daemon filesystem) documentation and JSON schema descriptions so they match the current implementation, and adds cross-links between the various ARC/DinD guidance surfaces.
Changes:
- Update
runner.topology,container.enableDind, andcontainer.dockerHostschema descriptions to reflect actual ARC/DinD behavior and security implications. - Document loopback TCP (
tcp://localhost:*/tcp://127.0.0.1:*) as an ARC/DinD auto-detection signal and add “See also” cross-references. - Add references to
arc-dind.mdfrom the usage/environment docs and include it in the config spec’s informative references.
Show a summary per file
| File | Description |
|---|---|
| docs/usage.md | Adds an ARC/DinD pointer from the --enable-dind section to the dedicated ARC/DinD guide. |
| docs/environment.md | Adds a “See also” cross-reference to the ARC/DinD guide from the env/config guidance. |
| docs/awf-config.schema.json | Updates schema descriptions for ARC/DinD topology and Docker host/DinD fields to better match implementation. |
| docs/awf-config-spec.md | Adds arc-dind.md to Informative References. |
| docs/arc-dind.md | Documents loopback TCP auto-detection and adds a “See also” section linking related references. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Low
| "topology": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "standard", | ||
| "arc-dind" | ||
| ], | ||
| "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF applies overridable defaults: network.isolation=true, dind.preStageDirs=true, sysroot image activation, and tool cache validation." | ||
| "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF enables sysroot staging (a sysroot-stage init container copies the build-tools image into a named volume mounted at /host:rw on the agent) and emits a warning when RUNNER_TOOL_CACHE points under /opt (which is typically invisible to the DinD daemon). Other ARC/DinD settings such as container.dockerHostPathPrefix, dind.preStageDirs, and network.isolation are configured explicitly through their own fields. See docs/arc-dind.md for a complete guide." | ||
| }, |
| "dockerHost": { | ||
| "type": "string", | ||
| "description": "Docker daemon socket or host to connect to (e.g. \"unix:///var/run/docker.sock\")." | ||
| "description": "Docker daemon socket URI for AWF's own operations (e.g. \"unix:///var/run/docker.sock\" or \"tcp://localhost:2375\"). Auto-detected from the DOCKER_HOST environment variable when not set explicitly. When combined with container.enableDind, AWF also mounts that socket inside the agent and sets the agent's DOCKER_HOST to the same URI so in-agent docker commands use the correct daemon. On ARC/DinD runners with a loopback TCP daemon (tcp://localhost:*), AWF detects the split-filesystem configuration automatically." | ||
| }, |
|
@copilot address review feedback |
|
✅ Copilot review passed with no inline comments. @copilot Add the |
✅ Coverage Check PassedOverall Coverage
📁 Per-file Coverage Changes (1 files)
Coverage comparison generated by |
|
📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤 |
|
✅ Build Test Suite completed successfully! |
|
✅ Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓 |
|
Chroot tests failed Smoke Chroot failed - See logs for details. |
|
📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅ |
|
🚀 Security Guard has started processing this pull request |
|
🔑 Smoke Copilot PAT PAT auth validated. All systems operational. ✅ |
|
✅ Smoke Gemini completed. All facets verified. 💎 Smoke test completed with failures. |
|
✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓 |
|
✅ Smoke Copilot BYOK AOAI (Entra) completed. Copilot AOAI BYOK (Entra) mode operational. 🔓 |
|
✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟 Smoke test in progress: build and GitHub reads passed; browser automation tool was not exposed in this session yet. |
|
✅ Contribution Check completed successfully! PR #5890 follows the applicable CONTRIBUTING.md guidelines based on the pre-fetched metadata, diffs, and contribution guide. Changes are documentation/schema-description only, the PR description is clear, documentation is updated, and no tests are required for new runtime functionality. |
|
✅ Smoke Claude passed |
Smoke Test Results
Overall: PASS — core connectivity verified.
Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
|
✅ Smoke Test: Copilot BYOK Mode - PASS
Running in direct BYOK mode via COPILOT_PROVIDER_API_KEY, credential injected at api-proxy sidecar. Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
Smoke Test: Claude Engine Validation
Overall Result: PASS Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
Smoke Test: Services Connectivity
Overall: FAIL — Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
Smoke Test Results
Running in direct BYOK mode (AWF_AUTH_TYPE=github-oidc + AWF_AUTH_AZURE_* + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw) authenticated via Microsoft Entra Overall: PASS cc Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
🔬 Smoke Test: API Proxy OpenTelemetry Tracing
All scenarios pass. ✅ Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
Smoke Test: Copilot PAT Auth — PASS✅ GitHub MCP connectivity: PR list confirmed Auth mode: PAT (COPILOT_GITHUB_TOKEN) Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
|
Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw) Overall: PASS Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
Gemini Engine Smoke Test Results
Overall Status: FAIL Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "localhost"See Network Configuration for more information.
|
|
Runner Doctor Updater: add cache-memory restore fallback key Warning Firewall blocked 2 domainsThe following domains were blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"
- "registry.npmjs.org"See Network Configuration for more information.
|
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — ✅ PASS Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "awmgmcpg"See Network Configuration for more information.
|
The
runner.topology: arc-dindschema description incorrectly claimed that setting this topology automatically enablesnetwork.isolation=trueanddind.preStageDirs=true. The implementation only enables sysroot staging and emits aRUNNER_TOOL_CACHEwarning — other settings must be configured explicitly. Docs also lacked cross-links between ARC/DinD surfaces and were missing the loopback TCP auto-detection case.Changes
docs/awf-config.schema.jsonrunner.topology(correctness fix): Remove false claim about automaticnetwork.isolation=true/dind.preStageDirs=truedefaults. Actual behavior: enablessysroot-stageinit container +sysroot:/host:rwvolume, emits/opttool-cache warning. Explicitly state other fields must be set independently.container.enableDind: Expand description to cover Docker socket exposure, DOCKER_HOST propagation, and security implication.container.dockerHost: Expand to cover DOCKER_HOST auto-detection,enableDindinteraction, and ARC/DinD loopback TCP detection.docs/arc-dind.mdtcp://localhost:*/tcp://127.0.0.1:*) to the auto-detection section — this pattern is handled byisSiblingDaemonSocket()but was undocumented.docs/awf-config-spec.mddocs/arc-dind.mdto Informative References.docs/environment.md/docs/usage.mdarc-dind.mdat the relevant ARC/DinD sections.